Research
Security News
Quasar RAT Disguised as an npm Package for Detecting Vulnerabilities in Ethereum Smart Contracts
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
troika-three-text
Advanced tools
The troika-three-text npm package is a library for rendering high-quality, performant text in Three.js scenes. It provides a simple and flexible way to add 3D text to your WebGL applications, with support for advanced features like custom fonts, text layout, and text effects.
Basic Text Rendering
This feature allows you to render basic 3D text in a Three.js scene. You can set the text content, font size, and position.
const { Text } = require('troika-three-text');
const text = new Text();
text.text = 'Hello, World!';
text.fontSize = 1;
text.position.set(0, 0, 0);
scene.add(text);
Custom Fonts
This feature allows you to use custom fonts by specifying the URL to a font file. This can be useful for branding or stylistic purposes.
const { Text } = require('troika-three-text');
const text = new Text();
text.text = 'Custom Font';
text.font = 'https://example.com/path/to/font.woff';
text.fontSize = 1;
text.position.set(0, 0, 0);
scene.add(text);
Text Effects
This feature allows you to apply various effects to the text, such as changing the color or adding glow effects. This can enhance the visual appeal of the text in your scene.
const { Text } = require('troika-three-text');
const text = new Text();
text.text = 'Glowing Text';
text.fontSize = 1;
text.position.set(0, 0, 0);
text.material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
scene.add(text);
The three-bmfont-text package is another library for rendering text in Three.js. It uses Bitmap fonts for text rendering, which can be more performant for certain use cases. However, it lacks some of the advanced features and flexibility of troika-three-text, such as support for custom fonts and text effects.
The three-mesh-ui package is designed for creating user interfaces in Three.js scenes. It supports text rendering along with other UI components like buttons and panels. While it offers a broader range of UI elements, it may not be as specialized or optimized for text rendering as troika-three-text.
The troika-three-text
package provides high quality text rendering in Three.js scenes, using signed distance fields (SDF) and antialiasing using standard derivatives.
Rather than relying on pre-generated SDF textures, this parses font files (.ttf, .otf, .woff) directly using Typr, and generates the SDF atlas for glyphs on-the-fly as they are used. It also handles proper kerning, ligature glyph substitution, right-to-left/bidirectional layout, and joined scripts like Arabic. All font parsing, SDF generation, and glyph layout is performed in a web worker to prevent frame drops.
Once the SDFs are generated, it assembles a geometry that positions all the glyphs, and patches any Three.js Material with the proper shader code for rendering the SDFs. This means you can still benefit from all the features of Three.js's built-in materials like lighting, physically-based rendering, shadows, and fog.
drei
utilities for react-three-fiberGet it from NPM:
npm install troika-three-text
You will also need to install a compatible version of Three.js; see the notes on Three.js versions in the Getting Started docs for details.
npm install three
import {Text} from 'troika-three-text'
You can then use the Text
class like any other Three.js mesh:
// Create:
const myText = new Text()
myScene.add(myText)
// Set properties to configure:
myText.text = 'Hello world!'
myText.fontSize = 0.2
myText.position.z = -2
myText.color = 0x9966FF
// Update the rendering:
myText.sync()
It's a good idea to call the .sync()
method after changing any properties that would affect the text's layout. If you don't, it will be called automatically on the next render frame, but calling it yourself can get the result sooner.
When you're done with the Text
instance, be sure to call dispose
on it to prevent a memory leak:
myScene.remove(myText)
myText.dispose()
Instances of Text
support the following configuration properties:
text
The string of text to be rendered. Newlines and repeating whitespace characters are honored.
Default: none
anchor
This property is deprecated as of version 0.24.0; use anchorX
and anchorY
instead.
anchorX
Defines the horizontal position in the text block that should line up with the local origin. Can be specified as a numeric x
position in local units, a string percentage of the total text block width e.g. '25%'
, or one of the following keyword strings: 'left'
, 'center'
, or 'right'
.
Default: 0
anchorY
Defines the vertical position in the text block that should line up with the local origin. Can be specified as a numeric y
position in local units (note: down is negative y), a string percentage of the total text block height e.g. '25%'
, or one of the following keyword strings: 'top'
, 'top-baseline'
, 'middle'
, 'bottom-baseline'
, or 'bottom'
.
Default: 0
clipRect
If specified, defines the [minX, minY, maxX, maxY]
of a rectangle outside of which all pixels will be discarded. This can be used for example to clip overflowing text when whiteSpace='nowrap'
.
Default: none
color
This is a shortcut for setting the color
of the text's material
. You can use this if you don't want to specify a whole custom material
and just want to change its color.
Use the material
property if you want to control aspects of the material other than its color.
Default: none - uses the color of the material
curveRadius
Defines a cylindrical radius along which the text's plane will be curved. Positive numbers put the cylinder's centerline (oriented vertically) that distance in front of the text, for a concave curvature, while negative numbers put it behind the text for a convex curvature. The centerline will be aligned with the text's local origin; you can use anchorX
to offset it.
Since each glyph is by default rendered with a simple quad, each glyph remains a flat plane internally. You can use glyphGeometryDetail
to add more vertices for curvature inside glyphs.
Default: 0
depthOffset
This is a shortcut for setting the material's polygonOffset
and related properties, which can be useful in preventing z-fighting when this text is laid on top of another plane in the scene. Positive numbers are further from the camera, negatives closer.
Be aware that while this can help with z-fighting, it does not affect the rendering order; if the text renders before the content behind it, you may see antialiasing pixels that appear too dark or light. You may need to also change the text mesh's renderOrder
, or set its z
position a fraction closer to the camera, to ensure the text renders after background objects.
Default: 0
direction
Sets the base direction for the text. The default value of "auto" will choose a direction based on the text's content according to the bidi spec. A value of "ltr" or "rtl" will force the direction.
Default: 'auto'
fillOpacity
Controls the opacity of just the glyph's fill area, separate from any configured strokeOpacity
, outlineOpacity
, and the material's opacity
. A fillOpacity
of 0
will make the fill invisible, leaving just the stroke and/or outline.
Default: 1
font
The URL of a custom font file to be used. Supported font formats are:
Default: The Roboto font loaded from Google Fonts CDN
fontSize
The em-height at which to render the font, in local world units.
Default: 0.1
glyphGeometryDetail
The number of vertical/horizontal segments that make up each glyph's rectangular plane. This can be increased to provide more geometrical detail for custom vertex shader effects, for example.
Default: 1
gpuAccelerateSDF
When true
, the SDF generation process will be GPU-accelerated with WebGL when possible, making it much faster especially for complex glyphs, and falling back to a JavaScript version executed in web workers when support isn't available. It should automatically detect support, but it's still somewhat experimental, so you can set it to false
to force it to use the JS version if you encounter issues with it.
Default: true
letterSpacing
Sets a uniform adjustment to spacing between letters after kerning is applied, in local world units. Positive numbers increase spacing and negative numbers decrease it.
Default: 0
lineHeight
Sets the height of each line of text. Can either be 'normal'
which chooses a reasonable height based on the chosen font's ascender/descender metrics, or a number that is interpreted as a multiple of the fontSize
.
Default: 'normal'
material
Defines a Three.js Material instance to be used as a base when rendering the text. This material will be automatically replaced with a new material derived from it, that adds shader code to decrease the alpha for each fragment (pixel) outside the text glyphs, with antialiasing.
By default it will derive from a simple white `MeshBasicMaterial, but you can use any of the other mesh materials to gain other features like lighting, texture maps, etc.
Also see the color
shortcut property.
Note that because your material instance is replaced by a derived material instance, any changes you make to your original material will not be reflected in the derived version. If you need to modify properties of the material afterward, be sure you get a new reference to the derived version:
// Bad:
text.material = myOrigMaterial
myOrigMaterial.opacity = 0.5
// Good:
text.material = myOrigMaterial
text.material.opacity = 0.5
Default: a MeshBasicMaterial
instance
maxWidth
The maximum width of the text block, above which text may start wrapping according to the whiteSpace
and overflowWrap
properties.
Default: Infinity
, meaning text will never wrap
outlineBlur
Specifies a blur radius applied to the outer edge of the text's outlineWidth
. If the outlineWidth
is zero, the blur will be applied at the glyph edge, like CSS's text-shadow
blur radius. A blur plus a nonzero outlineWidth
can give a solid outline with a fuzzy outer edge.
The blur radius can be specified as either an absolute number in local units, or as a percentage string e.g. "12%"
which is treated as a percentage of the fontSize
.
Default: 0
outlineColor
The color to use for the text outline when outlineWidth
, outlineBlur
, and/or outlineOffsetX/Y
are set. Accepts a ThreeJS Color
object, or a number/string accepted by Color#set
.
Default: black
outlineOffsetX
, outlineOffsetY
These define a horizontal and vertical offset of the text outline. Using an offset with outlineWidth: 0
creates a drop-shadow effect like CSS's text-shadow
; also see outlineBlur
.
The offsets can be specified as either an absolute number in local units, or as a percentage string e.g. "12%"
which is treated as a percentage of the fontSize
.
Default: 0
outlineOpacity
Sets the opacity of a configured text outline, in the range 0
to 1
.
Default: 1
outlineWidth
The width of an outline/halo to be drawn around each text glyph using the outlineColor
and outlineOpacity
. This can help improve readability when the text is displayed against a background of low or varying contrast.
The width can be specified as either an absolute number in local units, or as a percentage string e.g. "10%"
which is interpreted as a percentage of the fontSize
.
Default: 0
overflowWrap
Defines how text wraps if the whiteSpace
property is 'normal'
. Can be either 'normal'
to break at whitespace characters, or 'break-word'
to allow breaking within words.
Default: 'normal'
sdfGlyphSize
Allows overriding the default size of each glyph's SDF (signed distance field) used when rendering this text instance. This must be a power-of-two number. Larger sizes can improve the quality of glyph rendering by increasing the sharpness of corners and preventing loss of very thin lines, at the expense of increased memory footprint and longer SDF generation time.
Default: 64
strokeColor
The color of the text stroke, when strokeWidth
is nonzero. Accepts a ThreeJS Color
object, or a number/string accepted by Color#set
.
Default: grey
strokeOpacity
The opacity of the text stroke, when strokeWidth
is nonzero. Accepts a number from 0
to 1
.
Default: 1
strokeWidth
Sets the width of a stroke drawn inside the edge of each text glyph, using the strokeColor
and strokeOpacity
.
The width can be specified as either an absolute number in local units, or as a percentage string e.g. "10%"
which is interpreted as a percentage of the fontSize
.
Default: 0
textAlign
The horizontal alignment of each line of text within the overall text bounding box. Can be one of 'left'
, 'right'
, 'center'
, or 'justify'
.
Default: 'left'
textIndent
An indentation applied to the first character of each hard newline. Behaves like CSS text-indent
.
Default: 0
whiteSpace
Defines whether text should wrap when a line reaches the maxWidth
. Can be either 'normal'
, to allow wrapping according to the overflowWrap
property, or 'nowrap'
to prevent wrapping.
Note that 'normal'
in this context does honor newline characters to manually break lines, making it behave more like 'pre-wrap'
does in CSS.
Default: 'normal'
Since the text processing occurs in a web worker, it is by definition asynchronous. This means that you can't rely on the text being visible or having a complete geometry immediately. If you need to do things like access the geometry's boundingSphere
or the textRenderInfo
, you will have to listen for completion. You can do this two ways:
Pass a callback function when you call the sync
method:
myText.sync(() => {
// code to execute after sync completes...
})
This is best when you want to only react to that specific sync call. Keep in mind that the callback will not execute if the text is already fully synced.
Add a listener for the synccomplete
event:
myText.addEventListener('synccomplete', () => {
// code to execute after sync completes...
})
This will fire after every sync, no matter who invoked it. This is best if you need to react to all syncs, for example to trigger a manual canvas render.
You can also listen for the syncstart
event if you need to react to the initiation of a sync call, e.g. to set some sort of "waiting" state while the text is being processed.
To avoid long pauses when first displaying a piece of text in your scene, you can preload fonts and optionally pre-generate the SDF textures for particular glyphs up front:
import {preloadFont} from 'troika-three-text'
myApp.showLoadingScreen()
preloadFont(
{
font: 'path/to/myfontfile.woff',
characters: 'abcdefghijklmnopqrstuvwxyz'
},
() => {
myApp.showScene()
}
)
The arguments are:
options
options.font
- The URL of the font file to preload. If null
is passed, this will preload the default font.
options.characters
- A string or array of string character sequences for which to pre-generate glyph SDF textures. Note that this will honor ligature substitution, so you may need to specify ligature sequences in addition to their individual characters to get all possible glyphs, e.g. ["t", "h", "th"]
to get the "t" and "h" glyphs plus the "th" glyph.
options.sdfGlyphSize
- The size at which to prerender the SDFs for the characters
glyphs. See the sdfGlyphSize
config property on Text
for details about SDF sizes. If not specified, will use the default SDF size.
callback
- A function that will be called when the preloading is complete.
It is possible to use Text
within scenes that utilize the postprocessing library for applying image effects. However, you must enable a special mode in that library that allows Text
's custom material to be honored. Just do the following once somewhere in your code:
import { OverrideMaterialManager } from 'postprocessing'
OverrideMaterialManager.workaroundEnabled = true
In addition to rendering text, it is possible to access positioning information for caret placement and selection ranges. To access that info, use the getCaretAtPoint
and getSelectionRects
utility functions. Both of these functions take a textRenderInfo
object as input, which you can get from the Text
object's textRenderInfo
property after sync has completed. See "Handling Asynchronous Updates" above for how to react to sync completion events.
getCaretAtPoint(textRenderInfo, x, y)
This returns the caret position nearest to a given x/y position in the local text plane. This is useful for placing an editing caret based on a click or ther raycasted event. The return value is an object with the following properties:
x
- x position of the carety
- y position of the caret's bottomheight
- height of the caret, based on the current fontSize and lineHeightcharIndex
- the index in the original input string of this caret's target character. The caret will be for the position before that character. For the final caret position, this will be equal to the string length. For ligature glyphs, this will be for the first character in the ligature sequence.getSelectionRects(textRenderInfo, start, end)
This returns a list of rectangles covering all the characters within a given character range. This is useful for highlighting a selection range. The return value is an array of objects, each with {left, top, right, bottom}
properties in the local text plane.
FAQs
SDF-based text rendering for Three.js
We found that troika-three-text demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 0 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.